Node / meshtastic / Meshtastic-Android / files / docs / ht-rHT / user / mqtt.md

Displaying Rendered • View raw • Download

title: MQTT

parent: User Guide

nav_order: 11

last_updated: 2026-09-11

description: Bridge your mesh to the internet — MQTT broker setup, encryption layers, and map reporting.

aliases:

• mqtt

• internet-bridge

• broker

MQTT bridges your Meshtastic mesh network to the internet, enabling long-range communication beyond radio range.

The MQTT module connects your node to an MQTT broker, allowing:

• Messages to reach nodes on different physical meshes via the internet

• Integration with home automation and monitoring systems

• Publishing node positions to the public Meshtastic map

• Custom data pipelines for logging and alerting

T282828

A gateway node with internet access (Wi-Fi or Ethernet) publishes mesh messages to an MQTT topic. Remote gateways subscribed to the same topic inject those messages into their local mesh.

1. Navigate to Settings → Module configuration → MQTT.

2. Enable the MQTT module.

3. Configure the broker connection:

The top of the MQTT settings screen shows the status of the relay this phone runs —

Connected, Connecting, Reconnecting, Disconnected, or Inactive. It reads

Inactive whenever the phone is not relaying, which includes the normal case of a radio

reaching the broker over its own Wi-Fi or Ethernet. The radio's own connection to the broker is

not reported here.

Test connection probes the broker before you commit the settings to the radio, and

distinguishes the failure modes: the hostname not resolving, the TCP connection being refused,

TLS failing, the attempt timing out, or the broker rejecting your credentials with a reason.

If your radio has no internet access of its own, it can use the connected phone as its MQTT gateway: enable MQTT and Proxy to client enabled in the module config, and the app relays MQTT traffic between the radio and the broker over your phone's internet connection.

│ ℹ️ Note: The proxy relay is mobile-only. On the Desktop app the MQTT settings are present, but no

│ relay runs behind them.

The MQTT proxy on this phone toggle at the top of the MQTT settings screen shows whether this relay is running and lets you cut it off (or restart it) immediately — without editing and re-saving the radio's MQTT configuration.

The community maintains a public broker at T383838mqtt.meshtastic.org. This is intended for general use and testing.

When this phone relays MQTT for the radio, connections to that broker always use TLS on port 8883 even if TLS enabled is off — the app forces the switch on and grays it out. A radio that reaches the broker over its own Wi-Fi or Ethernet forces nothing: turn TLS enabled on yourself, or it connects in the clear on port 1883. For any other broker the toggle decides in both cases (port 8883 with TLS, 1883 without).

│ 🔒 Privacy: Messages on the public broker are readable by anyone subscribed. Always use channel

│ encryption for private communications.

For better privacy and control, you can run your own MQTT broker:

• Mosquitto (lightweight, open-source)

• HiveMQ

• EMQX

Configure your node to point to your private broker with appropriate credentials.

When Map reporting is on, your node periodically publishes a map report to the broker. The report goes out unencrypted, whatever keys your channels use, and carries your node id, long and short name, approximate location, hardware model, role, firmware version, LoRa region, modem preset, and primary channel name.

Turning it on opens a consent card. Turn on I agree. and choose a Map reporting interval (seconds) of one hour or more — the screen will not save until you do. A slider sets the position precision, and the app shows the resulting accuracy as a ± distance, so you can publish an approximate location rather than an exact one.

Reports appear at meshmap.net and similar community map services.

│ 🔒 Privacy: A map report is readable by anyone subscribed to the broker. Leave Map reporting off

│ if you do not want your approximate location published.

Uplink and downlink are per-channel settings, not MQTT module settings. Open Settings → Channels, tap the channel, and use MQTT Uplink Enabled and MQTT Downlink Enabled. Every channel you want bridged out needs uplink on, and every channel you want MQTT traffic injected into needs downlink on.

MQTT carries two payload formats:

│ ℹ️ Note: T383838json_enabled is marked deprecated in the protobuf schema, but it has not been replaced

│ and it is not ignored. When it is on, the app's own MQTT proxy subscribes to the T383838/2/json/ topic

│ and decodes those payloads.

Understanding the layered encryption model:

1. Channel encryption happens on the mesh before MQTT. If your channel has a PSK, the MQTT payload is already encrypted — the broker and any subscribers see only the ciphertext.

2. Encryption enabled (the module setting) decides which copy of the packet the gateway publishes — it is not an extra layer. Leave it on and the broker receives the packet still encrypted with your channel key. Turn it off and the gateway publishes the decrypted packet, so anyone subscribed to the topic reads your messages in the clear. Turn it off only when you own the broker and want plain payloads for a dashboard.

3. TLS encrypts the TCP connection to the broker itself, preventing network-level eavesdropping.

│ 🔒 Security: The default public channel has a well-known key. Messages on the default channel

│ sent via MQTT are effectively unencrypted — anyone can decode them. Always use a custom PSK for

│ private communications.

• Use channel-level encryption (PSK) on channels that bridge to MQTT

• Don't enable MQTT on nodes without internet access (the radio buffers unsendable messages and wastes memory)

• Use a private broker for sensitive deployments

• Be mindful of airtime when downlinking messages from busy MQTT topics — every downlinked message consumes radio airtime on your local mesh

• Consider enabling uplink-only if you only need to monitor your mesh remotely without injecting messages back

• Check Wi-Fi — the gateway node must have an active internet connection (Wi-Fi or Ethernet). MQTT does not work over the LoRa radio link itself.

• Verify credentials — with incorrect credentials, most brokers fail silently — double-check for trailing spaces.

• Firewall — port 1883 (MQTT) or 8883 (MQTT over TLS) must be reachable. Some networks allow only web traffic (ports 80 and 443).

• DNS resolution — if using a custom broker hostname, verify the node can resolve it. Try the broker's IP address directly.

• Check uplink/downlink settings — if only uplink is enabled, messages flow from mesh to MQTT but not back. Enable downlink on the receiving gateway.

• Channel mismatch — both gateways must share the same channel with the same PSK. A mismatch means messages are encrypted with different keys and appear as garbage.

• Topic mismatch — both gateways must use exactly the same root topic. Setting a region rewrites a default root to T383838msh/<REGION> (for example T383838msh/US), so gateways in different regions do not meet until you give both the same explicit root.

• Ignore MQTT is on — in a region with a duty-cycle limit, the radio turns on Ignore MQTT (LoRa config, Advanced) when you set the region, and then drops every packet that reached it via MQTT. Turn it off on the receiving nodes, not only on the gateway.

• Ok to MQTT is off — on a public broker a gateway uplinks other nodes' packets only when the sending node has Ok to MQTT (LoRa config, Advanced) on. Your own traffic bridges either way; your neighbors' does not until they opt in.

• Settings — Modules & Admin — MQTT module configuration reference

• Messages & Channels — channel encryption and PSK setup

• MQTT integration guide — detailed MQTT documentation on meshtastic.org